package com.air.mapper;


import com.air.annotation.AutoFill;
import com.air.dto.PassengerTicketPageQueryDTO;
import com.air.dto.TicketPageQueryDTO;
import com.air.entity.Ticket;
import com.air.enumeration.OperationType;
import com.air.vo.TicketVO;
import com.github.pagehelper.Page;
import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Select;
import org.apache.ibatis.annotations.Update;


import java.util.List;

@Mapper
public interface TicketMapper {
    /**
     * 添加机票。
     *
     * 本方法用于将给定的票务对象插入到数据库中，实现票务信息的持久化。
     * 通过使用@AutoFill注解，自动填充操作类型为INSERT，表明这是一个插入操作。
     *
     * @param ticket 待插入的票务对象，包含票务的相关信息。
     */
    @AutoFill(value = OperationType.INSERT)
    void insert(Ticket ticket);


    /**
     * 分页查询机票信息
     *
     * 本函数旨在根据提供的查询条件，进行机票信息的分页查询。查询结果将包含机票的详细信息，
     *
     *
     * @param ticketPageQuery 分页查询条件对象，包含查询参数和分页信息
     * @return 返回分页查询结果，包含查询到的机票信息和分页状态
     */
    Page<TicketVO> pageQuery(TicketPageQueryDTO ticketPageQuery);


    /**
     * 根据机票ID查询详细的机票信息。
     *
     * 此方法通过指定的ID从数据库中检索机票的详细信息。ID是机票的唯一标识符，
     * 通过这个ID可以精确地找到对应的机票记录。
     *
     * @param id 机票的唯一标识符，用于查询特定的机票。
     * @return 返回与给定ID匹配的机票对象。如果找不到匹配的记录，则返回null。
     */
    @Select("select * from ticket where id=#{id}")
    Ticket getById(Long id);


    /**
     * 批量删除操作接口。
     * 此方法旨在提供一种批量删除实体的途径，通过指定实体的ID列表来执行删除操作。
     *
     * @param ids 待删除实体的ID列表。此参数不应为空，且列表中的ID应为有效值。
     *            如果列表为空或包含无效ID，则可能导致删除操作失败或无操作。
     */
    void deleteBatch(List<Long> ids);


    /**
     * 根据机票ID查询机票详情及对应的航班信息。
     *
     * 本方法通过SQL查询语句关联了ticket表和flight表，以便获取机票的全部信息以及对应的航班号。
     * 使用左连接（left join）确保即使某些机票没有对应的航班信息，也能返回机票的其他信息。
     * 查询条件为机票表（ticket）中的ID与传入参数匹配。
     *
     * @param id 机票的唯一标识符
     * @return 返回匹配的机票对象，包含机票详情及航班信息
     */
    @Select("select t.*,f.flight_number from ticket t left join flight f on t.flight_id=f.id where t.id=#{id}")
    Ticket getByIdWithFlight(Long id);

    /**
     * 修改机票信息。
     *
     * 该方法通过接收一个机票对象来更新已存在机票的信息。使用了@AutoFill注解，自动填充操作类型为UPDATE，
     *
     * @param ticket 需要更新的机票对象，包含新的机票信息。
     */
    @AutoFill(value = OperationType.UPDATE)
    void update(Ticket ticket);


    /**
     * 根据航班ID查询机票信息。
     *
     * 通过左连接查询ticket表和flight表的数据，根据flight表的ID过滤结果。查询结果包括ticket表的所有列和flight表的flight_number列。
     * 此方法的目的是为了获取特定航班的所有机票信息，包括机票的基本信息和对应的航班号。
     *
     * @param ticket 机票对象，其中包含了要查询的航班ID。这个参数被用作查询条件。
     * @return 返回一个机票列表，这些机票都属于指定的航班。
     */
    @Select("select t.*,f.flight_number from ticket t left join flight f on t.flight_id = f.id where f.id=#{flightId}")
    List<Ticket> list(Ticket ticket);


    /**
     * 根据旅客信息进行分页查询机票
     *
     * 本方法通过接收旅客机票查询请求的数据传输对象（DTO），来进行机票的分页查询。
     * 主要用于在前端页面上展示旅客的机票信息，支持分页以提高数据加载效率。
     *
     * @param passengerTicketPageQueryDTO 旅客机票查询的页面请求DTO，包含查询条件和分页信息。
     * @return 返回分页查询结果，其中包含查询到的机票信息以及分页相关数据。
     */
    Page<TicketVO> pageQueryByPassenger(PassengerTicketPageQueryDTO passengerTicketPageQueryDTO);


    /**
     * 退票操作。
     *
     * 此方法用于实现机票的退票操作。通过接收机票ID，更新机票的退票状态。
     *
     * @param id 机票的唯一标识符，用于指定要退票的机票。
     */
    @Update("update ticket set status=1 where id=#{id}")
    @AutoFill(value = OperationType.UPDATE)
    void refund(Ticket ticket);
}
